Skip to content

feat(sdk): add standalone Agent SDK Host baseline - #1720

Merged
limityan merged 1 commit into
GCWing:mainfrom
limityan:yanzhn/sdk-host-runtime-contract
Jul 24, 2026
Merged

feat(sdk): add standalone Agent SDK Host baseline#1720
limityan merged 1 commit into
GCWing:mainfrom
limityan:yanzhn/sdk-host-runtime-contract

Conversation

@limityan

@limityan limityan commented Jul 23, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • add a standalone local bitfun-sdk-host composition root using newline-delimited JSON-RPC over stdio
  • keep Headless CLI, ACP, GUI/TUI, and SDK Host as sibling adapters over the same Agent Runtime owners
  • route SDK Query submission, cancellation, settlement, permissions, Tools, MCP, events, and transient Session cleanup through existing runtime ports
  • define strict initialize, Session, Query, cancellation, close, shutdown, capability, notification, and typed error contracts
  • bound data/control requests, active Queries, leased Sessions, output delivery, request drain, and total shutdown work
  • update the Agent SDK architecture document and module ownership guides to match the delivered boundary

Product boundary

This PR delivers an internal, standalone SDK Host implementation candidate. Its handshake reports not_delivered: it is not a public or stable SDK release, and this PR does not publish Python or TypeScript packages or claim full Claude Agent SDK parity.

Available in this baseline Explicitly deferred
initialize and capability negotiation public Python/TypeScript packages
connection-scoped transient Session create/close durable create/list/resume/fork
Query start/cancel with text deltas and one typed terminal result callback Tools, Permission callbacks, and Hook callbacks
existing BitFun Tool/MCP execution through shared Runtime owners managed Host supervision and pre-start authentication
bounded explicit shutdown and EOF cleanup TCP transport, MCP configuration APIs, usage and structured output

The Headless CLI does not depend on or start the SDK Host. The SDK Host does not depend on the CLI. They select separate delivery profiles and share only the stable Runtime/port layer and product assembly plan.

Architecture and safety

  • no second Agent loop, scheduler, Tool registry, MCP client, Permission engine, Session store, or CLI service graph
  • Query submit/cancel use the same scheduler owner, and terminal results are emitted only after exact Turn settlement
  • non-interactive SDK requests publish shared ToolContext facts and fail closed when user input is unavailable
  • transient Sessions cannot expose SessionControl, SessionMessage, SessionHistory, Cron, or ControlHub capabilities; the same restriction governs snapshots, subagent defaults, manifests, GetToolSpec, deferred Tool admission, and final execution admission
  • data and control requests use separate bounded budgets; shutdown bypasses request admission and shares one total deadline across drain, cancel, settlement, and cleanup
  • malformed envelopes, event loss, blocked output, and process loss produce typed bounded failures
  • a creation task that fails after Core creates a transient Session records the exact Session ID in a connection-owned cleanup ledger; shutdown owns compensation, retains failed entries, and cannot report success while cleanup remains incomplete
  • PTY/session ownership is released only after process exit is confirmed
  • interfaces/sdk-host is guarded from depending on bitfun-core, terminal-core, concrete services, the SDK Host app, or CLI; the concrete Host may use terminal-core only behind the shared Runtime TerminalPort

CI and test isolation

The Linux/macOS/Windows matrix runs the three terminal-core shutdown and binding regressions changed by this PR. It does not adopt the unrelated full terminal suite: an earlier broad gate exposed five existing Unix exec.rs failures in files this PR does not modify. Fixing those command-control tests is intentionally kept out of the SDK Host scope.

Standalone SDK Host process smokes are added on all three platforms. The Ubuntu crate-test lane continues to run the complete SDK Host/app contract and transport suites.

Independent whole-PR review

Three isolated reviewers audited the final rebased commit from architecture/lifecycle, product/competitor, and protocol/concurrency perspectives. All actionable findings were fixed, including CLI/Host dependency confusion, request concurrency, settlement/cancellation ownership, output failure handling, transient Tool projection, exact-ID cleanup after task failure, protocol envelope classification, and CI coverage.

Final result: P0 = 0, P1 = 0, P2 = 0.

Exact-head verification

Check Result
cargo check --locked --workspace passed
SDK Host lifecycle 31 passed
SDK Host protocol contracts 6 passed
SDK Host app transport/process tests 14 passed
Product SDK assembly 2 passed
SDK Host terminal cleanup regressions 3 passed
bitfun-services-core --no-default-features passed; dunce excluded
cargo test --locked -p bitfun-cli 326 unit tests and all integration suites passed
Core-boundary tests 16 passed
repository hygiene passed
git diff --check passed

@limityan
limityan force-pushed the yanzhn/sdk-host-runtime-contract branch 2 times, most recently from 02418cb to 4a1d3bf Compare July 24, 2026 04:32
@limityan limityan changed the title feat(sdk): add managed Agent SDK Host preview feat(sdk): add standalone Agent SDK Host baseline Jul 24, 2026
@limityan
limityan force-pushed the yanzhn/sdk-host-runtime-contract branch from 4a1d3bf to a02da08 Compare July 24, 2026 05:11
@limityan
limityan merged commit d7fca25 into GCWing:main Jul 24, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant